---
title: 部署你的 Astro 站点至 GitHub Pages
description: 如何使用 GitHub Pages 将你的 Astro 网站部署到网络上。
sidebar:
  label: GitHub Pages
type: deploy
logo: github
supports: ['static']
i18nReady: true
---
import { Steps } from '@astrojs/starlight/components';

你可以使用 [GitHub Pages](https://pages.github.com/) 直接从 [GitHub](https://github.com/) 上的存储库托管 Astro 网站。

## 如何部署

你可以使用 [GitHub Actions](https://github.com/features/actions) 将 Astro 站点自动构建和部署到 GitHub Pages。为此，你的源代码必须托管在 GitHub 上。

Astro 维护了一个官方的 GitHub Action `withastro/action` 来帮助你部署项目；你只需很少的配置，就可以完成部署。按照下面的说明可以将你的 Astro 站点部署到 GitHub Pages，如果你需要更多信息，请参阅[这个包的 README](https://github.com/withastro/action)。

## 为 GitHub Pages 配置 Astro

### 部署到 `github.io` 网址

在 `astro.config.mjs` 中配置文件设置 [`site`](/zh-cn/reference/configuration-reference/#site) 和 [`base`](/zh-cn/reference/configuration-reference/#base) 选项。

```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})
```

#### `site`

`site` 的值必须是以下之一：

- 基于你的用户名的以下网址：`https://<username>.github.io`
- 为 [GitHub 组织的私有页面](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) 自动生成的随机网址：`https://<random-string>.pages.github.io/`
    
#### `base`

可能需要为 `base` 设置一个值，以便 Astro 将你的仓库名称（例如 `/my-repo`）视为你网站的根目录。

:::note
  如果出现了以下情况，则不要设置 `base` 参数：

- 你的页面是由根文件夹所提供。
- 你的源码存储库是位于 `https://github.com/<USERNAME>/<USERNAME>.github.io`。
:::

`base` 的值应该是你的仓库名称，以正斜杠开头，例如 `/my-blog`。这样做是为了让 Astro 理解你的网站根目录是 `/my-repo`，而不是默认的 `/`。

:::caution
    当配置了这个值后，你所有的内部页面链接都必须以你的 `base` 值作为前缀：

```astro "/my-repo"
<a href="/my-repo/about">关于本站</a>
```

查看更多关于[配置 `base` 值](/zh-cn/reference/configuration-reference/#base)的信息。
:::

### 在 GitHub Pages 上使用自定义域名

:::tip[设置一个自定义域]
你可以选择通过将一个 `./public/CNAME` 文件添加到你的项目中，来设置自定义域：

```js title="public/CNAME"
sub.mydomain.com
```

这会将你的站点部署在你的自定义域而不是 `<YOUR_USERNAME>.github.io`。不要忘记[为你的域名提供商配置 DNS](https://docs.github.com/cn/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)。
:::

要配置 Astro 以在 GitHub Pages 上使用自定义域名，请将你的域名设置为 `site` 的值。不要为 `base` 设置值：

```js title="astro.config.mjs" ins={4}
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',
})
```

## 配置 GitHub Action

<Steps>
1. 在你的项目中的 `.github/workflows/` 目录创建一个新文件 `deploy.yml`，并粘贴以下 YAML 配置信息。

    ```yaml title="deploy.yml"
    name: Deploy to GitHub Pages

    on:
      # 每次推送到 `main` 分支时触发这个“工作流程”
      # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
      push:
        branches: [ main ]
      # 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
      workflow_dispatch:
      
    # 允许 job 克隆 repo 并创建一个 page deployment
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v3
            # with:
              # path: . # 存储库中 Astro 项目的根位置。（可选）
              # node-version: 20 # 用于构建站点的特定 Node.js 版本，默认为 20。（可选）
              # package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。（可选）

      deploy:
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
    ```
    
    :::note
    Astro GitHub Action 接受几个可选的设置项。你可以通过取消注释 `with:` 行和你想要使用的设置值来提供这些设置项。
    :::

    :::caution
    官方提供的 Astro [GitHub Action](https://github.com/withastro/action) 会扫描项目根目录下的 lockfile 以检测你首选的包管理器（`npm`、`yarn`、`pnpm` 或 `bun`）。你应该将包管理器自动生成的 `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml` 或 `bun.lockb` 文件提交到你的存储库。
    :::

2. （可选）如果你在本地开发期间或预览构建期间，将环境变量传入给 Astro 项目，则需要定义 `deploy.yml` 文件中的任何公共变量，以便在部署到 Github 页面时处理它们。（参阅 [Github 文档中关于设置机密](https://docs.github.com/zh/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) 以配置私密环境变量的部分。）

   ```yaml title="deploy.yml"
   jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v3
            env:
              # 使用单引号来包裹变量值
              PUBLIC_EVM_WALLET_ADDRESS: '0x4bFc229A40d41698154336aFF864f61083E76659'
   ```


3. 在 GitHub 上，跳转到存储库的 **Settings** 选项卡并找到设置的 **Pages** 部分。

4. 选择 **GitHub Actions** 作为你网站的 **Source**，然后按 **Save**。

5. 提交（commit）这个新的“工作流程文件”（workflow file）并将其推送到 GitHub。
</Steps>

你的网站现在应该已完成发布了！当你将更改推送到 Astro 项目的存储库时，GitHub Action 将自动为你部署它们。

## 示例

- [Github Pages 部署](https://github.com/hkbertoson/github-pages)
